---
layout: m1x_soap
title: Introduction to the Magento 1.x SOAP API
---

<ul class="introduction-menu">
    <li><a href='#Introduction-Introduction'>Introduction</a></li>
    <li><a href='#Introduction-SupportedTypes'>Supported Types</a>
        <ul>
            <li><a href='#Introduction-SOAP'>SOAP</a></li>
            <li><a href='#Introduction-XMLRPC'>XML-RPC</a></li>
        </ul>
    </li>
    <li><a href='#Introduction-APIMethods'>API Methods</a></li>
    <li><a href='#Introduction-GlobalAPIFaults'>Global API Faults</a></li>
    <li><a href='#Introduction-SOAPAPIVersionv2'>SOAP API Version v2</a></li>
</ul>

<h1><a name="Introduction-Introduction"></a>Introduction</h1>

<p>The Magento SOAP v1 API provides you with the ability to manage your eCommerce stores by providing calls for working with resources such as customers, categories, products, and sales orders. It also allows you to manage shopping carts and inventory.</p>

<p>A SOAP v2 API version has been available since Magento 1.3, and a WS-I compliant version has been available since Magento 1.6.</p>

<h2><a name="Introduction-SupportedTypes"></a>Supported Types</h2>

<p>The Magento API supports <a href="http://en.wikipedia.org/wiki/SOAP">SOAP</a> and <a href="http://en.wikipedia.org/wiki/XML_RPC">XML-RPC</a>, where SOAP is the default protocol.</p>

<h3><a name="Introduction-SOAP"></a>SOAP</h3>

<p>To connect to Magento SOAP web services, load the <a href="http://en.wikipedia.org/wiki/WSDL">WSDL</a> into your SOAP client from either of these URLs:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
        <pre class="theme: Default; brush: java; gutter: false">http://magentohost/api/?wsdl</pre>
        </div>
</div></div>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
        <pre class="theme: Default; brush: java; gutter: false">http://magentohost/api/soap/?wsdl</pre>
        </div>
</div></div>

<p>where magentohost is the domain for your Magento host.</p>

<p>As of v1.3, you may also use the following URL to access the Magento API v2, which has been added to improve compatibility with Java and .NET:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
        <pre class="theme: Default; brush: java; gutter: false">http://magentohost/api/v2_soap?wsdl=1</pre>
        </div>
</div></div>

<p>The following PHP example shows how to make SOAP calls to the Magento API v1:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
        <pre class="theme: Default; brush: php; gutter: false">$client = new SoapClient('http://magentohost/api/soap/?wsdl');

// If somestuff requires API authentication,
// then get a session token
$session = $client-&gt;login('apiUser', 'apiKey');

$result = $client-&gt;call($session, 'somestuff.method');
$result = $client-&gt;call($session, 'somestuff.method', 'arg1');
$result = $client-&gt;call($session, 'somestuff.method', array('arg1', 'arg2', 'arg3'));
$result = $client-&gt;multiCall($session, array(
     array('somestuff.method'),
     array('somestuff.method', 'arg1'),
     array('somestuff.method', array('arg1', 'arg2'))
));


// If you don't need the session anymore
$client-&gt;endSession($session);</pre>
        </div>
</div></div>

<h3><a name="Introduction-XMLRPC"></a>XML-RPC</h3>

<p>To use XML-RPC, load the following URL into your XML-RPC client:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
        <pre class="theme: Default; brush: java; gutter: false">http://magentohost/api/xmlrpc/</pre>
        </div>
</div></div>

<p>where magentohost is the domain for your Magento host.</p>

<p>The following PHP example shows how to make XML-RPC calls:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
        <pre class="theme: Default; brush: php; gutter: false">$client = new Zend_XmlRpc_Client('http://magentohost/api/xmlrpc/');

// If somestuff requires API authentication,
// we should get session token
$session = $client-&gt;call('login', array('apiUser', 'apiKey'));

$client-&gt;call('call', array($session, 'somestuff.method', array('arg1', 'arg2', 'arg3')));
$client-&gt;call('call', array($session, 'somestuff.method', 'arg1'));
$client-&gt;call('call', array($session, 'somestuff.method'));
$client-&gt;call('multiCall', array($session,
     array(
        array('somestuff.method', 'arg1'),
        array('somestuff.method', array('arg1', 'arg2')),
        array('somestuff.method')
     )
));

// If you don't need the session anymore
$client-&gt;call('endSession', array($session));</pre>
        </div>
</div></div>

<p>The XML-RPC only supports the version 1 of the Magento API.</p>

<h2><a name="Introduction-APIMethods"></a>API Methods</h2>

<p>The following table contains the API methods that can be called from your SOAP or XML-RPC client on the Magento v1 API.</p>



<table><tbody>
<tr>
<th> Method </th>
<th> Description </th>
<th> Return Value </th>
</tr>
<tr>
<td> startSession() </td>
<td> Start the API session and return session ID. </td>
<td> string </td>
</tr>
<tr>
<td> endSession(sessionId) </td>
<td> End the API session. </td>
<td> boolean </td>
</tr>
<tr>
<td> login(apiUser, apiKey) </td>
<td> Start the API session, return the session ID, and authorize the API user. </td>
<td> string </td>
</tr>
<tr>
<td> call(sessionId, resourcePath,array arguments) </td>
<td> Call the API resource that is allowed in the current session. See Note below. </td>
<td> mixed </td>
</tr>
<tr>
<td> multiCall(sessionId, array calls,array options) </td>
<td> Call the API resource’s methods that are allowed for current session. See Notes below. </td>
<td> array </td>
</tr>
<tr>
<td> resources(sessionId) </td>
<td> Return a list of available API resources and methods allowed for the current session. </td>
<td> array </td>
</tr>
<tr>
<td> globalFaults(sessionId) </td>
<td> Return a list of fault messages and their codes that do not depend on any resource. </td>
<td> array </td>
</tr>
<tr>
<td> resourceFaults(sessionId, resourceName) </td>
<td> Return a list of the specified resource fault messages, if this resource is allowed in the current session. </td>
<td> array </td>
</tr>
</tbody></table>

<p><b>Note:</b> For <b>call</b> and <b>multiCall</b>, if no session is specified, you can call only resources that are not protected by ACL.</p>

<p> <b>Note:</b> For <b>multiCall</b>, if the "break" option is specified, multiCall breaks on first error.</p>

<p>The Magento SOAP API v2 does not support the call() and multiCall() methods, and instead provides a separate method for each API resource.</p>

<h2><a name="Introduction-GlobalAPIFaults"></a>Global API Faults</h2>

<p>The following table contains fault codes that apply to all SOAP/XML-RPC API calls.</p>

<table><tbody>
<tr>
<th> Fault Code </th>
<th> Fault Message </th>
</tr>
<tr>
<td> 0 </td>
<td> Unknown Error </td>
</tr>
<tr>
<td> 1 </td>
<td> Internal Error. Please see log for details. </td>
</tr>
<tr>
<td> 2 </td>
<td> Access denied. </td>
</tr>
<tr>
<td> 3 </td>
<td> Invalid API path. </td>
</tr>
<tr>
<td> 4 </td>
<td> Resource path is not callable. </td>
</tr>
</tbody></table>


<h2><a name="Introduction-SOAPAPIVersionv2"></a>SOAP API Version v2</h2>

<p>Since Magento 1.3, version v2 of the SOAP API has also been available. The main difference between v1 and v2 is that instead of using methods call and multiCall, it has separate methods for each action.</p>

<p>For example, consider the following PHP code using SOAP v1.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
        <pre class="theme: Default; brush: php; gutter: false">$params = array(array(
    'status'=&gt;array('eq'=&gt;'pending'),
    'customer_is_guest'=&gt;array('eq'=&gt;'1'))
));
$result = $client-&gt;call($sessionId, 'sales_order.list', $params);</pre>
        </div>
</div></div>

<p>With SOAP v2, the following code would be equivalent.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
        <pre class="theme: Default; brush: php; gutter: false">$params = array('filter' =&gt; array(
    array('key' =&gt; 'status', 'value' =&gt; 'pending'),
    array('key' =&gt; 'customer_is_guest', 'value' =&gt; '1')
));
$result = $client-&gt;salesOrderList($sessionId, $params);</pre>
        </div>
</div></div>

<p>Note that the WSDL for SOAP v1 and SOAP v2 are different. Note that in SOAP v1, customizing the API did not involve changing the WSDL. In SOAP v2, changes to the WSDL are required.</p>

<p>You can configure the SOAP v2 API to be <a href="http://www.ws-i.org/">WS-I</a> compliant in the system configuration menu. To do this, set <b>Services &gt; Magento Core API &gt; WS-I Compliance</b> to <b>Yes</b>.</p>

<p>Note that the WSDL for the SOAP v2 API is different when in WS-I compliant mode.</p>

<p>Using the WS-I compliant SOAP v2 API WSDL, it is easy to automatically generate client classes for Java, .NET, and other languages using standard libraries. </p>



